
<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
    <title>Thinner -- Version 0.1.4</title>
    <link rel="stylesheet" type="text/css" href="documentation/css/styles.css" />
    <link rel="stylesheet" type="text/css" href="documentation/css/dawn.css" />
  </head>
  <body>
    <a href="http://www.propublica.org" class="propublica">&nbsp;</a>
    <h1>Thinner &ndash; Version 0.1.4</h1>
    <p><a href="https://github.com/propublica/thinner">Thinner</a> is a utility
      for purging urls from a Varnish server.</p>
    <p>When you are deploying code changes to a server under load, the uncached
       load can quickly bring down your backend server even with Varnish's grace
       mode. Often, allowing stale caches to stick around for a while saves
       both server performance and sanity.</p>
    <p>Thinner gives you fine-grained control over wildcard purging, and rolls
      purges out slowly. Your users will see stale pages from the previous deploy
      until Thinner has finished invalidating the stale cache at a rate that you set.
      If you have a bunch of pages you need to invalidate en masse and at infrequent
      intervals (e.g. deploys, timed remote api updates), but don't want to
      risk overloading your server, Thinner is for you.</p>
    <p>All that being said, Thinner isn't really a solution for observing
      model changes and purging associated urls. If you have a highly dynamic
      application, it's worlds better to handle purging via a
      <a href="http://github.com/russ/lacquer/blob/master/lib/lacquer/delayed_job_job.rb">job server</a>
      outside of the request-response flow.</p>
    <p><a href="doc/index.html">API docs</a> | <a href="http://github.com/propublica/thinner/issues">Issue Tracker</a></p>
    <h2>Installation</h2>
    <p>Thinner is available via rubygems:
    <pre>gem install thinner</pre>
    <h2>Usage</h2>
    <p>Thinner has both a library and command-line interface. To use it as a gem
      you'll first have to configure how it works by calling <strong>Thinner.configure</strong>.
      Here's a quick rundown of all of the options available:</p>
      <pre class="dawn"><span class="Support">Thinner</span><span class="PunctuationSeparator">.</span><span class="Entity">configure</span> <span class="Keyword">do </span><span class="PunctuationSeparator">|</span><span class="Variable">config</span><span class="PunctuationSeparator">|</span>
<span class="Comment">  <span class="Comment">#</span> Number of urls to purge at one time. These purge requests are fired in quick</span>
<span class="Comment">  <span class="Comment">#</span> succession. Thinner is perfectly capable of killing a Varnish server, by</span>
<span class="Comment">  <span class="Comment">#</span> overloading the worker thread, so be really conservative with this option.</span>
  config<span class="PunctuationSeparator">.</span><span class="Entity">batch_length</span> <span class="Keyword">=</span> <span class="Constant">10</span>

<span class="Comment">  <span class="Comment">#</span> The amount of time to sleep between purges in seconds.</span>
  config<span class="PunctuationSeparator">.</span><span class="Entity">sleep_time</span>   <span class="Keyword">=</span> <span class="Constant">1</span>

<span class="Comment">  <span class="Comment">#</span> The server address and management port. See:</span>
<span class="Comment">  <span class="Comment">#</span>   http://www.varnish-cache.org/trac/wiki/ManagementPort</span>
<span class="Comment">  <span class="Comment">#</span> for details.</span>
  config<span class="PunctuationSeparator">.</span><span class="Entity">server</span>       <span class="Keyword">=</span> &quot;127.0.0.1:6082&quot;

<span class="Comment">  <span class="Comment">#</span> By default, every time you call Thinner.purge! thinner spins off a new</span>
<span class="Comment">  <span class="Comment">#</span> instance of Thinner::Client and terminates any old instances that are</span>
<span class="Comment">  <span class="Comment">#</span> running. If you want to have overlapping instances set this to true.</span>
<span class="Comment">  <span class="Comment">#</span> It's not recommended to have multiple Thinner::Client's running at the</span>
<span class="Comment">  <span class="Comment">#</span> same time.</span>
  config<span class="PunctuationSeparator">.</span><span class="Entity">no_kill</span>      <span class="Keyword">=</span> <span class="Constant">false</span>

<span class="Comment">  <span class="Comment">#</span> The log file (either a string or file object) to log the current batch to.</span>
<span class="Comment">  <span class="Comment">#</span> Defaults to STDOUT</span>
  config<span class="PunctuationSeparator">.</span><span class="Entity">log_file</span>     <span class="Keyword">=</span> <span class="Variable">STDOUT</span>
<span class="Keyword">end</span>
</pre>
    <p>Once you have the configuration in place call <strong>purge!</strong> with
      an array of urls:</p>
      <pre class="dawn"><span class="Comment"><span class="Comment">#</span> The urls in this array are purged in order, so you'll want to structure it</span>
<span class="Comment"><span class="Comment">#</span> according to usage.</span>
arr <span class="Keyword">&lt;&lt;</span> [&quot;/some_route&quot;<span class="PunctuationSeparator">,</span> &quot;/some_route/with.*&quot;<span class="PunctuationSeparator">,</span> &quot;/&quot;]

<span class="Support">Thinner</span><span class="PunctuationSeparator">.</span><span class="Entity">purge!</span> arr
</pre>
    <p>Thinner will then fork a background process and purge the urls. You can
      check the progress of the purge by tailing the log file or with:</p>
      <pre>varnishlog | grep purge</pre>
    <p>If ruby's not your cup of tea, Thinner also has a command line interface.
      Once you've installed the gem run <strong>thinner -h</strong> to see the
      available options.</p>
    <p>The command line interface accepts a newline separated list of urls via
      stdin by setting the <strong>-e</strong> flag. So you'll be able to use
      the command like so:</p>
      <pre>cat urls_to_purge.txt | bin/thinner -e</pre>
    <h2>Change Log</h2>
    <h3>0.1.2</h3>
    <p>Force process to exit on signals and fixed gem warning.</p>
    <h3>0.1.1</h3>
    <p>Fixed bug in command line argument parsing.</p>
    <h3>0.1.0</h3>
    <p>Initial release.</p>
    </body>
</html>